Summary

Adds the initial Helper Causal Receipts v0.1 architecture spec for SourceOS Shell.

This captures the design response from the macOS unified-log helper-cascade analysis:

• root-intent-bound helper receipts
• declared helper spawn reasons
• capability request/decision receipts
• denial classification
• teardown normalization
• local-only preview policy profiles
• web-thumbnail hostile-content treatment
• native file picker isolation
• terminal preview secret isolation
• user-facing “Why did this run?” inspector requirements

Why this belongs in sourceos-shell

SourceOS Shell is the right runtime/spec home because it is the user-facing shell and receipt/inspector boundary for helper activity across preview, PDF/document rendering, browser integration, terminal integration, and local-first observability.

Downstream repos should align to this contract:

• SourceOS-Linux/BearBrowser: browser file picker, cache cleanup, preview, web thumbnail enforcement
• SourceOS-Linux/TurtleTerm: terminal preview helper isolation and shell-secret denial
• SocioProphet/ontogenesis: ontology + SHACL vocabulary
• SocioProphet/prophet-platform: evidence envelope mapping and CI trust gates

Validation

• Documentation-only PR.
• Local artifact packet produced parser/correlator/fixtures and validation separately.
• Future implementation PRs should add schema, policy YAML, parser/correlator, and CI gates after this architecture contract is accepted.

Follow-up implementation checklist

• Add JSON Schema for sourceos.helper_causal_receipt.v0.1.
• Add policy YAML profiles.
• Add helper wrapper runtime.
• Add receipt store.
• Add “Why did this run?” inspector.
• Add parser/correlator tooling for imported logs.
• Add CI checks for local-only preview invariants.